3 * Copyright (c) 2007-2009 Ariel Flesler - aflesler(at)gmail(dot)com | http://flesler.blogspot.com
\r
4 * Dual licensed under MIT and GPL.
\r
7 * @projectDescription Easy element scrolling using jQuery.
\r
8 * http://flesler.blogspot.com/2007/10/jqueryscrollto.html
\r
9 * Works with jQuery +1.2.6. Tested on FF 2/3, IE 6/7/8, Opera 9.5/6, Safari 3, Chrome 1 on WinXP.
\r
11 * @author Ariel Flesler
\r
14 * @id jQuery.scrollTo
\r
15 * @id jQuery.fn.scrollTo
\r
16 * @param {String, Number, DOMElement, jQuery, Object} target Where to scroll the matched elements.
\r
17 * The different options for target are:
\r
18 * - A number position (will be applied to all axes).
\r
19 * - A string position ('44', '100px', '+=90', etc ) will be applied to all axes
\r
20 * - A jQuery/DOM element ( logically, child of the element to scroll )
\r
21 * - A string selector, that will be relative to the element to scroll ( 'li:eq(2)', etc )
\r
22 * - A hash { top:x, left:y }, x and y can be any kind of number/string like above.
\r
23 * - A percentage of the container's dimension/s, for example: 50% to go to the middle.
\r
24 * - The string 'max' for go-to-end.
\r
25 * @param {Number} duration The OVERALL length of the animation, this argument can be the settings object instead.
\r
26 * @param {Object,Function} settings Optional set of settings or the onAfter callback.
\r
27 * @option {String} axis Which axis must be scrolled, use 'x', 'y', 'xy' or 'yx'.
\r
28 * @option {Number} duration The OVERALL length of the animation.
\r
29 * @option {String} easing The easing method for the animation.
\r
30 * @option {Boolean} margin If true, the margin of the target element will be deducted from the final position.
\r
31 * @option {Object, Number} offset Add/deduct from the end position. One number for both axes or { top:x, left:y }.
\r
32 * @option {Object, Number} over Add/deduct the height/width multiplied by 'over', can be { top:x, left:y } when using both axes.
\r
33 * @option {Boolean} queue If true, and both axis are given, the 2nd axis will only be animated after the first one ends.
\r
34 * @option {Function} onAfter Function to be called after the scrolling ends.
\r
35 * @option {Function} onAfterFirst If queuing is activated, this function will be called after the first scrolling ends.
\r
36 * @return {jQuery} Returns the same jQuery object, for chaining.
\r
38 * @desc Scroll to a fixed position
\r
39 * @example $('div').scrollTo( 340 );
\r
41 * @desc Scroll relatively to the actual position
\r
42 * @example $('div').scrollTo( '+=340px', { axis:'y' } );
\r
44 * @dec Scroll using a selector (relative to the scrolled element)
\r
45 * @example $('div').scrollTo( 'p.paragraph:eq(2)', 500, { easing:'swing', queue:true, axis:'xy' } );
\r
47 * @ Scroll to a DOM element (same for jQuery object)
\r
48 * @example var second_child = document.getElementById('container').firstChild.nextSibling;
\r
49 * $('#container').scrollTo( second_child, { duration:500, axis:'x', onAfter:function(){
\r
50 * alert('scrolled!!');
\r
53 * @desc Scroll on both axes, to different values
\r
54 * @example $('div').scrollTo( { top: 300, left:'+=200' }, { axis:'xy', offset:-20 } );
\r
58 var $scrollTo = $.scrollTo = function( target, duration, settings ){
\r
59 $(window).scrollTo( target, duration, settings );
\r
62 $scrollTo.defaults = {
\r
64 duration: parseFloat($.fn.jquery) >= 1.3 ? 0 : 1
\r
67 // Returns the element that needs to be animated to scroll the window.
\r
68 // Kept for backwards compatibility (specially for localScroll & serialScroll)
\r
69 $scrollTo.window = function( scope ){
\r
70 return $(window)._scrollable();
\r
73 // Hack, hack, hack :)
\r
74 // Returns the real elements to scroll (supports window/iframes, documents and regular nodes)
\r
75 $.fn._scrollable = function(){
\r
76 return this.map(function(){
\r
78 isWin = !elem.nodeName || $.inArray( elem.nodeName.toLowerCase(), ['iframe','#document','html','body'] ) != -1;
\r
83 var doc = (elem.contentWindow || elem).document || elem.ownerDocument || elem;
\r
85 return $.browser.safari || doc.compatMode == 'BackCompat' ?
\r
87 doc.documentElement;
\r
91 $.fn.scrollTo = function( target, duration, settings ){
\r
92 if( typeof duration == 'object' ){
\r
93 settings = duration;
\r
96 if( typeof settings == 'function' )
\r
97 settings = { onAfter:settings };
\r
99 if( target == 'max' )
\r
102 settings = $.extend( {}, $scrollTo.defaults, settings );
\r
103 // Speed is still recognized for backwards compatibility
\r
104 duration = duration || settings.speed || settings.duration;
\r
105 // Make sure the settings are given right
\r
106 settings.queue = settings.queue && settings.axis.length > 1;
\r
108 if( settings.queue )
\r
109 // Let's keep the overall duration
\r
111 settings.offset = both( settings.offset );
\r
112 settings.over = both( settings.over );
\r
114 return this._scrollable().each(function(){
\r
117 targ = target, toff, attr = {},
\r
118 win = $elem.is('html,body');
\r
120 switch( typeof targ ){
\r
121 // A number will pass the regex
\r
124 if( /^([+-]=)?\d+(\.\d+)?(px|%)?$/.test(targ) ){
\r
125 targ = both( targ );
\r
129 // Relative selector, no break!
\r
130 targ = $(targ,this);
\r
132 // DOMElement / jQuery
\r
133 if( targ.is || targ.style )
\r
134 // Get the real position of the target
\r
135 toff = (targ = $(targ)).offset();
\r
137 $.each( settings.axis.split(''), function( i, axis ){
\r
138 var Pos = axis == 'x' ? 'Left' : 'Top',
\r
139 pos = Pos.toLowerCase(),
\r
140 key = 'scroll' + Pos,
\r
142 max = $scrollTo.max(elem, axis);
\r
144 if( toff ){// jQuery / DOMElement
\r
145 attr[key] = toff[pos] + ( win ? 0 : old - $elem.offset()[pos] );
\r
147 // If it's a dom element, reduce the margin
\r
148 if( settings.margin ){
\r
149 attr[key] -= parseInt(targ.css('margin'+Pos)) || 0;
\r
150 attr[key] -= parseInt(targ.css('border'+Pos+'Width')) || 0;
\r
153 attr[key] += settings.offset[pos] || 0;
\r
155 if( settings.over[pos] )
\r
156 // Scroll to a fraction of its width/height
\r
157 attr[key] += targ[axis=='x'?'width':'height']() * settings.over[pos];
\r
159 var val = targ[pos];
\r
160 // Handle percentage values
\r
161 attr[key] = val.slice && val.slice(-1) == '%' ?
\r
162 parseFloat(val) / 100 * max
\r
166 // Number or 'number'
\r
167 if( /^\d+$/.test(attr[key]) )
\r
168 // Check the limits
\r
169 attr[key] = attr[key] <= 0 ? 0 : Math.min( attr[key], max );
\r
172 if( !i && settings.queue ){
\r
173 // Don't waste time animating, if there's no need.
\r
174 if( old != attr[key] )
\r
175 // Intermediate animation
\r
176 animate( settings.onAfterFirst );
\r
177 // Don't animate this axis again in the next iteration.
\r
182 animate( settings.onAfter );
\r
184 function animate( callback ){
\r
185 $elem.animate( attr, duration, settings.easing, callback && function(){
\r
186 callback.call(this, target, settings);
\r
193 // Max scrolling position, works on quirks mode
\r
194 // It only fails (not too badly) on IE, quirks mode.
\r
195 $scrollTo.max = function( elem, axis ){
\r
196 var Dim = axis == 'x' ? 'Width' : 'Height',
\r
197 scroll = 'scroll'+Dim;
\r
199 if( !$(elem).is('html,body') )
\r
200 return elem[scroll] - $(elem)[Dim.toLowerCase()]();
\r
202 var size = 'client' + Dim,
\r
203 html = elem.ownerDocument.documentElement,
\r
204 body = elem.ownerDocument.body;
\r
206 return Math.max( html[scroll], body[scroll] )
\r
207 - Math.min( html[size] , body[size] );
\r
211 function both( val ){
\r
212 return typeof val == 'object' ? val : { top:val, left:val };
\r
